Microsoft Office 365 Remote Library Object
From APA 7.3, the Real-Time Designer provides functionality for connecting directly to a Microsoft Office 365 server and handling Microsoft Outlook 365 email resources. By connecting directly to the server, your solution can work with Outlook 365 email resources without Outlook installed on the Real-Time Client machine.
The Mark Email As Unread function was added in APA 7.4, together with support for additional parameters in existing functions.
In APA 7.7, the Add Recipient(s) to Outlook Email and Move Email to Folder functions were added.
For details on incorporating this functionality into your solutions, see Using Microsoft Outlook 365.
This library includes the following business entities:
-
Exchange 365 Connection, found in Business Entities > Library Types > Microsoft Outlook, which contains the properties and functions you need to establish an authenticated connection with an Office 365 server. For details, see Exchange 365 Connection Business Entity.
-
Outlook Email, found in Business Entities > Library Types > Microsoft Outlook, which contains the properties you need to work with Outlook 365 email messages. For details, see Outlook Email Business Entity.
-
Outlook Attachment Info, found in Business Entities > Library Types > Microsoft Outlook, which contains the properties you need to work with Outlook 365 email message attachments. For details, see Outlook Attachment Info Business Entity.
The library functions are exposed under Project > References > Library References > Direct.MsOffice.Remote.Library. For details, see Microsoft Office 365 Library Functions.
Authentication
The following authentication methods are supported:
-
Implicit (Windows Integrated)
-
Client Credentials
-
Interactive (pop-up window)
Permissions
The following permissions need to be granted on the Microsoft identity platform:
| API/Permissions name | Description |
|---|---|
|
Mail.ReadWrite |
Read and write access to user mail |
|
Mail.Send |
Send mail as a user |
|
User.Read |
Sign in and read user profile |
Exchange 365 Connection Business Entity
The Exchange 365 Connection business entity contains the properties and functions for establishing an authenticated connection with an Office 365 server. This business entity is found in Business Entities > Library Types > Microsoft Outlook.
A successful connection to the Office 365 server is a precondition for using the functions that access Outlook 365 email resources, described in Microsoft Office 365 Library Functions. If the connection gets disconnected, you will have to connect again for your solution to continue working.
The Exchange 365 Connection business entity includes the following properties:
|
Property |
Input Type |
Description |
|---|---|---|
| Application Id | Text |
The ID of the application requesting permissions on behalf of a user to access Office 365 resources. This ID is only meaningful in the context of the hosting tenant. Your network administrator will need to configure the application ID and provide it to you. |
| Tenant Id | Text |
The ID of the tenant of the Microsoft Identity Platform, through which Office 365 applications access Office 365 resources. The tenant is usually an organization. Your network administrator will need to provide you with this value. |
| Is Connected | Boolean | A read-only Boolean property that indicates if a connection has been established with the Office 365 server. The value of this property is updated to True when the connection succeeds, and to False when the connection is disconnected. while the value of this property is False, all the functions that require access to Outlook 365 email resources will fail. |
Once you have defined an instance of the Exchange 365 Connection business entity, use one of the following functions to connect to the Office 365 server.
Connect As Windows User
Connects to the Office 365 server using the credentials that were used to log into a shared-trust Windows domain. This authentication method can only be used with work or school accounts. It is not available for personal accounts.
This function does not use any parameters.
Returns
N/A
Connect Interactive
Connects to the Office 365 server by opening a pop-up dialog box that directs the user to complete authentication by providing details such as the account and the relevant credentials. Use this method if consent to access Office 365 has not been given by the tenant administrator. This authentication method can be used with personal accounts, as well as with work or school accounts.
This function does not use any parameters.
Returns
N/A
Connect With User and Password
Connects to the Office 365 server using the specified username and password. This authentication method is not recommended, as storing a username and password as part of the solution is a serious security breach. If you need to use this method, we recommend you use a Credentials Server, which is a Real-Time Designer component for storing sensitive data and pulling it at runtime. This authentication method can be used with personal accounts, as well as with work or school accounts.
| Parameter | Input | Description |
|---|---|---|
|
User |
Text |
The username with which to connect to the Office 365 server. |
|
Password |
Text |
The password with which to connect to the Office 365 server. |
Returns
N/A
Disconnect
Disconnects from the Office 365 server. It is recommended to always disconnect using this function when you no longer require access to the Office 365 server.
This function does not use any parameters.
Returns
N/A
Outlook Attachment Info Business Entity
The Outlook Attachment Info business entity found in Business Entities > Library Types > Microsoft Outlook holds email message attachment details.
The Outlook Attachment Info business entity includes the following properties:
|
Property |
Input Type |
Description |
|---|---|---|
| ContentType | Text | The MIME type of the attachment content. |
| Id | Text | A unique identifier of the attachment, assigned by the server. This is used in the function Download Attachment to identify the attachment to be downloaded. |
| Is Inline | Boolean |
Indicates if the attachment is an inline attachment or a non-inline attachment. Currently only non-inline attachments are supported, so the value of this property is always False. |
| Name | Text |
A friendly string identifier of the attachment. |
| Size | Number | The size of the attachment, in bytes. |
Outlook Email Business Entity
The Outlook Email business entity found in Business Entities > Library Types > Microsoft Outlook holds email message details.
Typically, Outlook Email objects are returned by the functions Get Emails or Get Matching Emails, and can then be manipulated, for example by forwarding or deleting them. The exception is Send Email, for which you need to build an Outlook Email object before you can send it.
The Outlook Email business entity includes the following properties:
|
Property |
Input Type |
Description |
|---|---|---|
| Attachments Info | List of Outlook Attachment Info |
A list of the Outlook Attachment Info business entities that hold the details of the attachments of this email message. |
| Body | Text |
The content of the email message. |
| Cc | List of Text | A list of valid email addresses of the CC recipients of the email message. |
| Has Attachments | Boolean | Indicates if the email message has at least one attachment (True), or no attachments (False) (read-only). |
| Id | Text | The ID of the email message, assigned by the Office 365 server (read-only). |
| Is HTML | Boolean | Indicates if the email message content is HTML formatted (True), or not HTML formatted (False) (read-only). |
| Is Read | Boolean | Indicates if the email message has been read (True) or not (False) (read-only). |
| Preview | Text | A text preview of the email message content (read-only). |
| Received DateTime | DateTime | The date and time the email message was received (read-only). |
| Sender | Text | A valid email address of the email message sender (read-only). |
| Sent DateTime | DateTime | The date and time the email message was sent (read-only). |
| Subject | Text | The email message subject. |
| To | List of Text | A list of valid email addresses of the direct recipients of the email message. |
The Outlook Email business entity includes the following function:
Add Attachment
Adds a specified file to an email message as an attachment.
| Parameter | Input | Description |
|---|---|---|
|
Full Path |
Text |
The full path of the file (text) to be attached to the email when it is sent. |
Microsoft Office 365 Library Functions
The library functions for accessing and manipulating Outlook 365 email resources are exposed under Library Objects > Direct.MsOffice.Remote.Library > Microsoft Exchange 365.
Successful authentication by the Office 365 server is a precondition for using these functions. They all accept an Exchange 365 Connection business entity as their first parameter, and this connection must already be established in order for the functions to succeed. For details, see Exchange 365 Connection Business Entity.
Add Recipient(s) to Outlook Email
Adds recipients to Outlook email.
| Parameter | Input | Description |
|---|---|---|
|
Outlook Email |
Outlook Email |
An Outlook Email object. |
| To Email Address(es) | List of Text | A list of valid email address(es) to add to the email message. |
| CC Email Address(es) | List of text | A list of text specifying email address(es) of CC recipients. |
Returns
N/A
Delete Email
Deletes an email message.
| Parameter | Input | Description |
|---|---|---|
|
Connection |
Exchange 365 Connection |
An Exchange 365 Connection business entity that has established a connection with the Office 365 server. |
|
Email Id |
Text |
The ID of the email message to be deleted, as specified by the Id property of an Outlook Email object retrieved using the functions Get Emails or Get Matching Emails. |
Returns
N/A
Download Attachment
Downloads an attachment from an email message.
| Parameter | Input | Description |
|---|---|---|
|
Connection |
Exchange 365 Connection |
An Exchange 365 Connection business entity that has established a connection with the Office 365 server. |
|
Email Id |
Text |
The ID of the email message from which to download the attachment, as specified in the Id property of an Outlook Email object retrieved using the functions Get Emails or Get Matching Emails. |
| Attachment ID | Text | The ID of the attachment to be downloaded, as specified by the Id property of an Outlook Attachment Info object. |
| Path | Text | The local path to which to save the attachment. |
| Overwrite | Boolean | Indicates if an existing file with the same name in the specified folder is overwritten. If the value of this parameter is True and a file with the same name exists in the specified folder, it will be overwritten. If the value of this parameter is False and a file with the same name exists in the specified folder, the file will not be overwritten and the function will fail. |
Returns
Returns a Boolean value of True if the attachment is successfully downloaded, otherwise returns False if the attachment cannot be downloaded for any reason.
Forward Email
Forwards an email message.
| Parameter | Input | Description |
|---|---|---|
| CC | List of text | A list of text specifying email address(es) of cc recipients |
| Comment | Text | Additional text to include with the forwarded email, in the same format the original email. |
|
Connection |
Exchange 365 Connection |
An Exchange 365 Connection business entity that has established a connection with the Office 365 server. |
|
Outlook Email |
Outlook Email |
An Outlook Email object retrieved using the functions Get Emails or Get Matching Emails. |
| To Email Address(es) | List of Text | A list of valid email address(es) to which to forward the email message. |
Returns
N/A
Get Email Folders
Gets the names of all the Outlook folders for the user.
| Parameter | Input | Description |
|---|---|---|
|
Outlook Connection |
Outlook Connection |
An Exchange 365 Connection business entity that has established a connection with the Office 365 server. |
Returns
A list of strings of the Outlook folders for the user, in '\{Root Folder}\{Sub-Folder}\{Sub-Sub-Folder}\...' format. For example, '\Inbox', '\Deleted Items', '\Inbox\Manager'.
Get Emails
Gets email messages from the user's Outlook 365 mailbox.
| Parameter | Input | Description |
|---|---|---|
|
Connection |
Exchange 365 Connection |
An Exchange 365 Connection business entity that has established a connection with the Office 365 server. |
|
Max Number of Emails |
Number |
The maximum number of email messages to retrieve from the specified folder. The email messages are retrieved from newest to oldest. |
| Folder | Text |
The Outlook folder from which to retrieve the email messages, in '\{Root Folder}\{Sub-Folder}\{Sub-Sub-Folder}\...' format. If the value of this parameter is empty or null, it is ignored, and email messages will be retrieved from any folder |
| Only Unread | Boolean | Indicates if only unread email messages should be retrieved from the specified folder (True), or if both read and unread email messages should be retrieved (False). |
| Mark As Read | Boolean | Indicates if email messages retrieved from the specified folder should be marked as Read (True), or if Unread email messages should remain marked Unread (False). |
Returns
A list of Outlook Email objects that meet the function criteria.
Get Matching Emails
Gets email messages that match the function criteria from the user's Outlook 365 mailbox. Any criterion that is missing or invalid is ignored. Only email messages that meet all the valid criteria are retrieved.
| Parameter | Input | Description |
|---|---|---|
|
Connection |
Exchange 365 Connection |
An Exchange 365 Connection business entity that has established a connection with the Office 365 server. |
|
Max Number of Emails |
Number |
The maximum number of email messages to retrieve from the specified folder. The email messages are retrieved from newest to oldest. |
| Folder | Text |
The Outlook folder from which to retrieve the email messages, in '\{Root Folder}\{Sub-Folder}\{Sub-Sub-Folder}\...' format. If the value of this parameter is empty or null, it is ignored, and email messages will be retrieved from any folder |
| Sender's Email | Text | A valid email address of the email message sender. |
| Subject | Text | An email message will be retrieved as long as the parameter value appears in the subject line. It does not need to be an exact match. |
| From Date | DateTime | The date range of emails to retrieve. Only email messages sent after this date will be retrieved. |
| To Date | DateTime | The date range of emails to retrieve. Only email messages sent before this date will be retrieved. |
| Mark As Read | Boolean | Indicates if email messages retrieved from the specified folder should be marked as Read (True), or if Unread email messages should remain marked Unread (False). |
Returns
A list of Outlook Email objects that meet the function criteria.
Mark Email As Read
Marks an email message as Read.
| Parameter | Input | Description |
|---|---|---|
|
Connection |
Exchange 365 Connection |
An Exchange 365 Connection business entity that has established a connection with the Office 365 server. |
|
Email Id |
Text |
The ID of the email message to mark as Read, as specified in the Id property of an Outlook Email object retrieved using the functions Get Emails or Get Matching Emails. |
Returns
N/A
Mark Email As Unread
Marks an email message as Unread.
| Parameter | Input | Description |
|---|---|---|
|
Connection |
Exchange 365 Connection |
An Exchange 365 Connection business entity that has established a connection with the Office 365 server. |
|
Email Id |
Text |
The ID of the email message to mark as Read, as specified in the Id property of an Outlook Email object retrieved using the functions Get Emails or Get Matching Emails. |
Returns
N/A
Move Email to Folder
Moves an email message from one folder to another.
| Parameter | Input | Description |
|---|---|---|
|
Connection |
Exchange 365 Connection |
An Exchange 365 Connection business entity that has established a connection with the Office 365 server. |
|
Email Id |
Text |
The ID of the email message to move, as specified in the Id property of an Outlook Email object retrieved using the functions Get Emails or Get Matching Emails. |
| Folder | Text |
The Outlook folder from which to retrieve the email messages, in '\\{Email Address}\{Root Folder}\{Sub-Folder}\{Sub-Sub-Folder}\...' format. |
Returns
N/A
Reply Email
Replies to an email message.
| Parameter | Input | Description |
|---|---|---|
| CC | List of text | A list of text specifying email address(es) of cc recipients |
|
Connection |
Exchange 365 Connection |
An Exchange 365 Connection business entity that has established a connection with the Office 365 server. |
|
Outlook Email |
Outlook Email |
An Outlook Email object retrieved using the functions Get Emails or Get Matching Emails. |
| Reply All | Boolean | Indicates if the reply should be sent to all the email message recipients (True), or only to the email message sender (False). |
| Reply Text | Text | The reply text, in the same format as the original email. |
Returns
N/A
Send Email
Sends an email message with the specified subject and body to the specified recipients.
| Parameter | Input | Description |
|---|---|---|
|
Connection |
Exchange 365 Connection |
An Exchange 365 Connection business entity that has established a connection with the Office 365 server. |
|
To Email Address(es) |
List of Text |
A list of valid email addresses of the direct recipients to whom to send the email message. |
| Cc Email Address(es) | List of Text | A list of valid email addresses of the CC recipients to whom to send the email message. |
| Subject | Text | The subject of the email message. |
| Body | Text | The textual body of the email message. |
Returns
N/A
Send HTML Email
Sends an email message in HTML format with the specified subject and body to the specified recipients.
| Parameter | Input | Description |
|---|---|---|
|
Connection |
Exchange 365 Connection |
An Exchange 365 Connection business entity that has established a connection with the Office 365 server. |
|
To Email Address(es) |
List of Text |
A list of valid email addresses of the direct recipients to whom to send the email message. |
| Cc Email Address(es) | List of Text | A list of valid email addresses of the CC recipients to whom to send the email message. |
| Subject | Text | The subject of the email message. |
| Body | Text | The textual body of the email message in HTML format. |
Returns
N/A
Send Outlook Email
Sends an email message using a specified Outlook Email object.
| Parameter | Input | Description |
|---|---|---|
|
Connection |
Exchange 365 Connection |
An Exchange 365 Connection business entity that has established a connection with the Office 365 server. |
|
Outlook Email |
Outlook Email |
An Outlook Email object that has at least one valid email address defined in its To property. For details, see Outlook Email Business Entity. |
Returns
N/A
Send HTML Outlook Email
Sends an email message in HTML format using a specified Outlook Email object.
| Parameter | Input | Description |
|---|---|---|
|
Connection |
Exchange 365 Connection |
An Exchange 365 Connection business entity that has established a connection with the Office 365 server. |
|
Outlook Email |
Outlook Email |
An Outlook Email object that has at least one valid email address defined in its To property. For details, see Outlook Email Business Entity. |
| Body | Text | The textual body of the email message in HTML format. |
Returns
N/A
